Languguage OS 2/Languguage OS II Version 10-94 (Knowledge Media)(1994).ISO/language/c/cc_pp/v020/configur

Text File | 1994-10-30 | 18KB | 402 lines

This document describes the configuration/installation process for CC++
and lists the resource requirements and supported platforms.

The CC++ anonymous ftp site is cs.caltech.edu in the /comp/CC++ directory.

ABOUT CC++:
-----------

CC++ is a parallel programming language that extends the C++ programming
language.  The current CC++ compiler is implemented as a CC++ to C++
source to source transformer together with a runtime library which supports
threads and communication.  The CC++ transformer is written in C++ and the
CC++ runtime library is written in C++ and C.  The current version of
the runtime library is built on communication primitives provided by
PVM.  In order to build CC++ from source, a C++ compiler is needed that
can build the CC++ transformer and the CC++ runtime library.  In addition,
an ANSI C compiler is needed to build parts of the CC++ runtime library.
Finally, a target (backend) C++ compiler is needed which can compile the
output of the CC++ to C++ source to source transformer.  Typically, the
same C++ compiler is used as a target C++ compiler as is used to
build the CC++ transformer and runtime.  Note that prebuilt (precompiled)
versions of the CC++ transformer and runtime library are available.
Read the following sections for more information.

RESOURCE REQUIREMENTS:
----------------------

The following requirements are approximate and were generated by
measuring the space used when CC++ was built on a SPARCstation
running SunOS 4.1.2 and using the sunCC C++ compiler.

DISK

When unpacked, the cc++ source directory requires about 8MB of disk.
If desired, the CC++ source directory may be removed after CC++ is built
and installed.

If the cc++ compiler is built using the -O3 (or -O2) option and _not_ using the
-g option (-O2 or -O3 being the usual case for end-user installations), the
installation directory requires about 3.5 MB of disk space.  The build
directory (which may be removed following the 'make install') requires about
9.5 MB of disk space.

If the cc++ compiler is built using the -g (debugging) option, the
installation directory requires about 9.5 MB of disk space.  The build
directory (which may be removed following the 'make install') requires about
46 MB of disk space (varies depending on which C++ compiler and hardware
platform is used to build cc++).  Note that the -g flag need not be used
unless you plan to debug the CC++ compiler itself (as opposed to debugging
programs written in CC++).

RAM

The current release of CC++ requires a large amount of RAM and
virtual memory (swap space) in order to be fast enough to be useful (and
to avoid thrashing your machine).  The CC++ RAM requirements should become
more moderate in future releases.  The following are rough estimates only:
CC++ can use 40MB or more of memory when compiling large CC++ programs.
As a bare minimum, CC++ needs at least 16MB of real RAM.  CC++ will do
much better with 32MB of RAM and better still with 48MB of real RAM.
Swap space should be large enough to make the virtual memory
of the machine be large enough to handle as many simultaneous CC++
users as you expect to have.  We have found 64MB of swap is a good lower
bound.  Many of our machines have 128MB of swap space.  Note that programs
compiled using CC++ will likely have memory requirements similar to those of
equivalent C++ programs using libraries to obtain parallelism.

---------------------
SOFTWARE REQUIREMENTS
---------------------

CC++ Version 0.2 has been successfully built and installed under the
following combinations of host operating system, C++ compiler, and threads
packages.  If unsure what operating system is installed at your site, try
using the 'uname -a' command to find out.

operating system:     SunOS 4.1.2
C++ compiler:         sunCC SC2.0.1 (Sun's C++)
thread package:       FSU's pthreads (modified for use with CC++)

operating system:     SunOS 4.1.2
C++ compiler:         CenterLine C++ version 2.2
thread package:       FSU's pthreads (modified for use with CC++)

operating system:     SunOS 4.1.2
C++ compiler:         USL cfront C++ 3.0.1
thread package:       FSU's pthreads (modified for use with CC++)

operating system:     SunOS 4.1.3
C++ compiler:         sunCC SC2.0.1 (Sun's C++)
thread package:       FSU's pthreads (modified for use with CC++)

operating system:     Solaris 2.2
C++ compiler:         sunCC SC2.0.1 (Sun's C++)
thread package:       Solaris threads (comes with Solaris 2.2)

operating system:     Solaris 2.3
C++ compiler:         sunCC SC2.0.1 (Sun's C++)
thread package:       Solaris threads (comes with Solaris 2.3)

operating system:     AIX 3.2
C++ compiler:         xlC (IBM AIX XL C++ Compiler/6000)
thread package:       IBM's DCE threads (available from IBM)

As of CC++ version 0.2, the Sun C++ (SunOS 4.1.2 and Solaris 2.2) and
AIX 3.2 combinations are the only ones that have been reasonably well tested.
Note that some older versions of the CenterLine compiler aren't able to build
CC++.  CC++ may also build correctly under Solaris 2.1 but this hasn't been
tested.  CC++ will not yet build correctly under G++ (GNU's C++) because of a
bug in G++'s implementation of virtual functions when used in conjunction with
multiple inheritance.  If and when this G++ bug is fixed, CC++ may become
buildable using G++.

PVM

The CC++ runtime library targets Nexus which currently uses version 3.2.x of
the PVM library and environment from Oak Ridge National Laboratory (ORNL) as
an underlying interhost communication mechanism.  CC++ requires PVM to be
installed (although it is possible to run CC++ programs without having a pvm
daemon running).  Earlier versions of PVM may also work with CC++.  The CC++
distribution does not contain PVM.  The latest release of PVM should be
available via anonymous ftp in /netlib/pvm3 on netlib.att.com.  PVM
installation instructions are included with the PVM distribution.  The CC++
release notes contain some information on using PVM in conjunction with CC++.

The CC++ configuration script needs to be able to find where PVM is
installed on your system.  If pvm is not installed in each user's home
directory (under the name 'pvm3'), then the environment variable
PVM_ROOT needs to be set in each user's .cshrc or .profile.  This
variable should point to the PVM installation directory (e.g.
setenv PVM_ROOT /usr/local/pvm3).

BISON

In order to build CC++ from scratch, you will need a copy of GNU's bison
(yacc clone).  The CC++ grammar depends on some of the special extra
features available in bison and will not build correctly if yacc is used
instead.  Bison may be obtained via anonymous ftp from prep.ai.mit.edu
in the /pub/gnu directory.  After obtaining bison, follow the bison
build and installation instructions.  Be sure to install bison in
a directory that is in your PATH environment variable.

Note: a prebuilt (already compiled) version of cctran is available for
various different platforms.  If a prebuilt version is available for your
platform of choice and if you choose to use it, then bison is not needed.
See the 'PREBUILT CC++' section for more information.

ANSI C Compiler

The contents of the ./nexus subdirectory need to be built using an ANSI
C Compiler.  CC++ is configured to use 'acc' under SunOS4 and 'cc' otherwise.
The C compiler used to compile Nexus may be changed by setting the
NEXUS_TARGET_CC variable inside the appropriate mh-${host_os} file
(e.g. mh-sunos4) which is in the cc++/config directory.  Run configure
after making any changes to the config files.

FSU PTHREADS

The SunOS 4.1.2 CC++ uses a slightly modified version of FSU's pthreads package.
This modified version will be made available via ftp from the same location
from which CC++ is available.  To configure and install pthreads (which
should be done _before_ configuring and installing CC++) do the following:

   1) obtain pthreads via ftp from the CC++ ftp site.
   2) configure it using the 'configure' script in the pthreads directory
      and the same -prefix= flag that you plan to use to configure CC++.
      An example invocation is as follows:
          configure -prefix=/usr/local/CC++/install
   3) run 'make' and 'make install' from within the pthreads directory.

Pthreads must be configured and built from within the pthreads
source directory (the pthreads distribution doesn't yet support multiple
builds from the same source directory).  Also, one of the pthreads
files requires the unbundled SunOS assembler 'as' (we haven't had any success
with using GNU's gas or /usr/bin/as to build it).  For those sites
running SuNOS 4.1.x without the unbundled SunOS compiler package,
we have made a precompiled version of the pthreads library available
in the CC++ ftp site.  See the 'PREBUILT CC++' section for more information.

PREPROCESSORS

In order to compile and use CC++, you will need a C++ compiler that
uses an ANSI C preprocessor (cpp).  Some C++ compilers (such as AT&T's cfront
under SunOS 4.1.x) may not by default use an ANSI C preprocessor.  If when
configuring CC++, an error message is printed regarding the lack of an ANSI C
preprocessor, you will need to source the following C-shell script (source
scriptname).  This script is only required during the building of CC++.  It
isn't required to run CC++ (in fact, it will likely cause problems if used
in a shell prior to running CC++ in that shell).

#---begins---
# Set cppC to point to an ANSI C preprocessor.  This path will likely
# differ for different sites.
setenv cppC /ufs/comp/sun4/lib/gcc-lib/sun4/2.4.5/cpp
#
# Uncomment the following line for older versions of GNU's cpp
#setenv CPPFLAGS -B
#
# Uncomment the following line for newer versions of GNU's cpp
setenv CPPFLAGS -lang-c++
#----ends----

Be sure to only use the above script when using AT&T's cfront
since not doing so will prevent the configure command from succeeding
(e.g. using the above script will cause the configure to fail when
using CenterLine C++).  If using AT&T cfront and you find that cpp
is crashing, try building CC++ from within the CC++ source directory
rather than from a separate build directory (cfront can generate
#line directives that will crash some cpp's).  We have successfully
built CC++ using AT&T cfront together with sunCC's 'cc'.  We have
yet to successfully build CC++ using cfront together with gcc
(undefined symbol __main).

-------------
CONFIGURATION
-------------

Before CC++ can be built, it must be configured for the particular system
on which it is to be installed.  To accomplish this, use the 'configure'
script in the root directory of the distribution.  This script reads
configuration files stored in the ./config directory.  You will need to
customize a 'site' file (e.g. ms-caltech) to reflect the particulars of the
site at which CC++ is to be installed.

EXAMPLE MS-CONFIG SITE FILE

#--- begins ---
# ms-caltech: Configuration for optimized CC++ compiler performance
CCC=CC
CC=cc

# CCFLAGS for CC (C++)
CCFLAGS_OPTIMIZE=-O3
CCFLAGS_DEBUG=

# CFLAGS for cc (C)
CFLAGS_OPTIMIZE=-O3
CFLAGS_DEBUG=
#--- ends ---

The CCC variable specifies which C++ compiler to use when building
CC++.  This should be set to the same C++ compiler that is to be used
for the backend C++ compiler (the C++ compiler which compiles the
transformed CC++ produced by the frontend of CC++ (cctran)).  The
reason for this requirement is that the code to be linked by the
backend C++ must link with the CC++ runtime library produced by the
C++ compiler which compiled CC++.  Supposedly the object modules
produced by different compilers should be combinable into one executable
but in practice this sometimes is not the case (e.g. with CenterLine).

The CC variable specifies which C compiler to use (many of the files
in the ./cc++/parser directory are C files).

The CCFLAGS_OPTIMIZE variable specifies which optimization flags to
use when compiling the CC++ compiler.  Appropriate values for this
variable will vary depending on the host OS and compiler being used.

The CCFLAGS_DEBUG variable specifies which debugging flags to use
when compiling the CC++ compiler.  Typical values for this are -g
(for debugging the CC++ compiler with dbx or gdb) or -pg (for profiling
the CC++ compiler).

The CFLAGS_OPTIMIZE and CFLAGS_DEBUG variables are for setting the
optimization and debugging flags used when compiling those parts of
the CC++ distribution that are written in C.

Here is an example usage of the 'configure' script:

configure -prefix=/usr/local/cc++/install -site=caltech \
   -target_CCC=/ufs/comp/CenterLine/bin/CC

The prefix flag specifies the directory in which to install CC++.  The site
flag specifies which ms-config file to use from the ./config directory.
E.g. -site=caltech specifies that 'configure' should use ./config/ms-caltech.

The target_CCC flag may be used to specify a backend C++ compiler other
than the default.  If target_CCC is not specified then the configure
script will choose a C++ compiler to use based on the platform being
used (e.g. CC on Suns, xlC on RS/6000).

The 'configure' script will determine the operating system and architecture
automagically (this information need not be provided via flags to
'configure').

If your system has more than one C++ compiler installed under the same
name but in different directories (e.g. CC is a common name for C++
compilers), then make sure that the C++ compiler specified by
-target_CCC is in fact the one which is invoked when you type
'CC'.  The order of the directories in your PATH environment variable
may need to be changed to ensure that the correct C++ (CC) is found.
Try using the 'which CC' command to determine which CC will be found
when 'CC' is executed.

------------
INSTALLATION
------------

After configuring CC++, build and install it by typing:

  make

followed by:

  make install

The configuration, compiling, and installation may take quite some time
(a couple of hours or more) depending on the speed of the target machine
and disk (and the optimization level chosen for the C++ compiler used to
compile CC++).

PREBUILT CC++

In case you would like to avoid long compile times or have or want to
get bison and/or ANSI C, we have made available prebuilt (precompiled)
distributions of CC++ for various platforms.  These prebuilt distributions
are available from the CC++ ftp site and will be named sunos4.1.2-pre.tar.Z,
aix3.2-pre.tar.Z, etc.  Note that the prebuilt distributions are supplements
to the standard CC++ distribution and not as a replacement; that is, the
prebuilt distribution requires source files from the standard distribution in
order to build a working cc++ binary.  Installing the prebuilt version of
CC++ typically takes around five minutes on a SPARCstation LX.

If using the prebuilt distribution, make sure to unpack cc++, pthreads
(if using SunOS 4.1.2), and the prebuilt distribution into the same
parent directory.  This is necessary so that the 'make prebuilt' process can
find the precompiled binaries and libraries.  One directory structure
that would work is as follows:

/usr/local/CC++/cc++
/usr/local/CC++/pthreads
/usr/local/CC++/prebuilt

If you choose to use the prebuilt CC++, use the following three configuration
and installation steps.

0) Create the installation directory (e.g. mkdir /usr/local/CC++/install)
   that you plan to specify via the -prefix= option to 'configure'.

1) Configure the pthreads directory (if using SunOS 4.1.2) as described
   in the FSU PTHREADS section.  Inside the pthreads directory, type
   'make prebuilt' and 'make install-prebuilt'

2) Configure the 'cc++' directory as described in the CONFIGURATION
   section (this cc++ directory is created when the standard cc++
   distribution is unpacked).

3) Inside the cc++ directory, type 'make prebuilt' and 'make install-prebuilt'

At this point CC++ is installed and ready to use (if all went well).
See the 'RUNNING THE CC++ COMPILER' section.

MULTIPLE BUILD DIRECTORIES

If building the CC++ compiler for multiple platforms it is convenient
to use the same source tree for all of the builds.  This dramatically
reduces the disk space required for handling multiple builds (assuming
the various hosts share a filesystem via NFS or some other equivalent
mechanism).  To take advantage of this possibility, simply invoke the
'configure' script from the directory in which you'd like CC++ to be
built (this directory should not be the same directory as used by the
CC++ source).

E.g. if the CC++ distribution is stored in $HOME/src/cc++ then you might
want to create a directory $HOME/config/host_os/compiler for each target
host_os/compiler combination (with the words host_os and compiler replaced
with appropriate values).  Then from within the $HOME/config/host_os/compiler
directory, type:

$HOME/src/cc++/configure -prefix=the_install_dir -site=the_site_config_file

Note that this method will only work if a 'configure' has never been
performed from within the $HOME/src/cc++ directory.

FOR MORE INFORMATION

For more detailed information on the configure utility, see the GNU
documents "cfg-paper.texi, and configure.*" in the ./cc++/docs directory.

-------------------------
RUNNING THE CC++ COMPILER
-------------------------

Before using CC++ make sure that the CC++ bin directory is in your
PATH environment variable (the directory that contains the executable
named "cc++") in your .login or .profile file (depending on which shell
you use).  The easiest way to ensure this is to put the cc++ binary
in a standard location such as /usr/local/bin that is already in
everyone's path.

See the CC++ man page (type 'man cc++') for more information on the various
command line flags/options available in CC++.  Also read the CC++ tutorial
(cc++-tutorial.ps) and try the example programs (examples.tar.gz) to become
familiar with using CC++.

---------------------
RUNNING CC++ PROGRAMS
---------------------

If using CC++ on a machine running the Solaris 2.x OS, be sure to add
/usr/ucblib to your LD_LIBRARY_PATH environment variable (in $HOME/.cshrc
or $HOME/.profile depending on which shell you use).